ObiWan is dedicated to beta testers and freeware and shareware authors.
“ObiWan is a must-have”
- Australian&New Zealand MacUser, Pg 88, Nov 1993.
• Contents
What ObiWan Does
Features
Using ObiWan
Using Master Yoda
Database Format
How It Works
Limitations
Small Print
Warranty
Fine Print
Version History
Acknowledgements
• What ObiWan Does
ObiWan is a general help system. You can create several databses and ObiWan will let you rapidly find information from them. It displays the information by popping up a floating window so the information can be displayed at any time in any program. Portions of the information can then be sent to the front window as if you had typed it. The main use of all this is to access the programming database created from Apple’s PInterfacesHelp file and many other sources, which includes the procedures, traps, global variables and errors available up to System 7. Also included is a word list and Perl help database. ObiWan requires System 7.1 (for the Text Services Manager).
• Features
The Force file includes all the System 7 information.
The Force database is quite up to date, including lots of the new managers.
Any number of databases may exist, only one of which is active at any time.
First word searches are instantaneous, general searches are very quick.
Databases are plain text files and can be edited at any time they are not active.
Databases are reindexed automatically when the file size changes.
Database file size is unlimited.
Databases can have any number of entries.
There is absolutely no dependency on MacTCP at all.
Caveats:
Clicks occasionally get lost. Anyone from Apple care to comment why sometimes jGNEFilter isn’t called?
Keys typed in to ObiWan also go into a DA window if a DA is front-most.
The Finder doesn't like having keys dumped at it for some reason.
• Using ObiWan
Make an alias to ObiWan and drop it in the Startup Items folder in your System folder. Launch it.
ObiWan silently waits in the background for you to press cmd-` at which time it will pop up a window and let you find entries in the database. Type cmd-` (hold down the cloverleaf key and press the back-quote key (`)). Read the help there, or type "a" and a return to redisplay the help text. Click on the arrows to move thru the database. Double-click on words to find their entry.
NOTE: sometimes clicks will disappear. This is due to a bug in the system, and there is nothing I can do about it at this stage.
The buttons and their respective keys are, from left to right:
Lookup <return>
Search Anywhere <shift-return>
Move Backwards <cmd-,>
Move Forewards <cmd-.>
Jump Back <cmd-[>
Type Word <cmd-enter>
Type Line <cmd-option-enter>
Type Procedure <cmd-shift-enter>
Type Entire Entry <cmd-option-shift-enter>
Play sound at launch (toggles the preference)
Play sound at invokation (toggles the preference)
About
Change Database or Parse Procedure <option-return>
NOTE: The startup and invokation sounds have been removed from the Metrowerks distributed version to avoid any copyright problems.
The Force database is partially produced by parsing the PInterfacesHelp file which I have license from Apple. Thanks to Rick Fleischman, Barbara Napier, and Apple Computer, Inc. for waiving the fee to allow the Force file to be distributed. The Force file contains all the System 6 and 7 procedures, constants, errors, and global variables. You can find these by opening ObiWan (cmd-`), typing in the start of the name (eg HOpen) and pressing return. You can then insert the routine into THINK Pascal or C or MPW by clicking the third insert button (the one that looks like a procedure) (or by typing cmd-shift-enter). Note that there is a Pascal bias in this database because I am biased towards Pascal, but there is no reason some bright spark couldn’t produce a C equivalent database. You can also look up traps, errors, globals by searching for:
trapA000 - four digit hex number, starting with A
err-108 - decimal number, starting with a minus for OSErrs
err25 - decimal number, positive for system errors.
global910 - three digit hex number for global variables. (QuickDraw globals are not included)
You can change to using the C Parse Procedure by typing “C<option-return>”
The Force database is not special in any way (except that it contains the programming information for System 7). You can create other databases and switch between them by typing the name <name> and clicking the change button (furthest to the right) (or typing <option-return>). Other databases that are might be available include: a word dictionary (included); a thesaurus (both based on Roget's thesaurus from the Gutenburg project); a perl database (included); a Newton database (out of date now) and possibly a unix database (similar to Force, but for unix commands).
• Using Master Yoda
Launch Master Yoda.
Click the Select button to select a database, then you can get Stats on the database, sort it, add another (sorted!) database, index the database (but that is done automatically for you anyway), or change the word set characters for the database.
• Database Format
An ObiWan database is just a TEXT file with a strict format, plus some resources in the resource fork, including the index (which is recalculated if the file size changes) the word character set. The format of the text file is (by example):
=|
indexword data
general stuff, up to 10 lines, each up to 80 characters, ending with a|
nextindexword more data
more stuff|
verynextindexedword more and more data
finally ending with|
=|
The file should be sorted by the indexword (Master Yoda’s sort sorts by the entire entry so if you want related parts to stay in the same order when the database is sorted, they must be ordered in that way). The sort order is straight ASCII, case insensitive. Yes, I can hear you screaming “No, no, use the language independent sort order that the system defines”, (and yes, I do think that comma should go outside the quote mark irrespective of what the English teachers would have you believe :-) but I wish to be able to distribute a database file that works on all machines without having to be resorted.
Let’s see if I can define a BNF for the database format:
character ::= chr(9) | chr(32)..chr(126) | chr(128)..chr(255)
lines MUST be at most 80 characters, and should fit into the window in Geneva 9.
entries MUST be at most 10 lines.
There is no limit to the file size or number of entries (well, ok, the file size is limited by the file system, but thats not my fault, and the number of entries is obviously limited by the size of the file...)
Note: The file absolutely must start and end with =|<cr>. No trailing blank lines.
• How It Works
ObiWan uses the Text Services manager to display the floating window (and thus requires System 7.1), and patches into the jGNEFilter list to receive events, although not all clicks manage to get to the jGNEFilter list, which is unfortunate.
Later on, it watches keypresses and if a match for the popup key appears it opens the display window and accepts key strokes. When you hit return it takes the first eight letters of the word (padding with zeros), and scans thru an index to find where in the database that word comes, then it positions itself in the database and scans the entries until it finds a matching one and displays that. The “anywhere” search is done using Boyer-Moore search routine - this is one of the most elegant and simple routines I’ve ever seen, if you ever do any searching code, check this out, it is hardly any more complicated than a brute force search, but takes time *inversely* proportional to the length of the search string!
Entering characters into the front application is done by simply returning key down events (with key codes) in response to null events. Word still gets confused (because it only calls WNE if there is an event waiting), but thats to be expected.
• Limitations
ObiWan & Master Yoda require System 7.1 or later.
There is a problem with clicks in ObiWan’s display area sometimes being ignored. This happens because the click is sometimes stolen before it gets to the jGNEFilter. I have no idea why this would happen, nor why it happens only sometimes. If anyone has any ideas, please let me know.
There is also a problem that key presses go into DA windows instead of ObiWan. I don’t really think this is a major problem, but perhaps others disagree.
If you quit ObiWan (using ProcessWatcher for example), the icon remains greyed out in the Finder. This is a bug in the Finder.
• Small Print
This program is totally free. That’s right, pay nothing now, pay nothing later (but don’t expect me to send you a steak knife or any jewellery :-). If you like it and use it you can show your appreciation by:
Sending me some Email or a Poastcard.
Donating Blood.
Giving me a free trip to wherever you are, or anywhere else.
Picking up some litter.
Or anything else you feel like doing :-)
You MAY NOT DISTRIBUTE this program on any disk costing more than $5 without my explicit permission.
• Warranty
This program should do what I’ve described in this document. If it doesn’t, you can simply stop using it. I’d refund your money, but since it’s free anyway…
• Fine Print
Peter Lewis hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implied warranties of merchantability or fitness for a particular purpose. Peter Lewis will not be liable for any special, incidental, consequential, indirect or similar damages due to loss of data or any other reason, even if Peter Lewis or an agent of his has been advised of the possibility of such damages. In no event shall Peter Lewis be liable for any damages, regardless of the form of the claim. The person using the software bears all risk as to the quality and performance of the software.
APPLE COMPUTER, INC. ("APPLE") MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING MPW. APPLE DOES NOT WARRANT, GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OR THE RESULTS OF THE USE OF MPW IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS OR OTHERWISE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF MPW IS ASSUMED BY YOU. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.
IN NO EVENT WILL APPLE, ITS DIRECTORS, OFFICERS, EMPLOYEES OR AGENTS BE LIABLE FOR CONSEQUENCTIAL, INCIDENTAL OR INDIRECT DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE) ARISING OUT OF THE USE OR INABILITY TO USE MPW EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
BECAUSE SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITIES FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU. Apple's liabilities to you for actual damages for any cause whatsoever, and regardless of the form of the action (whether in contract, tort (including negligence), product liability or otherwise), will be limited to $50.
And that goes double for Peter Lewis.
US Governement:
Government End Users: If you are acquiring the Software and fonts
on behalf of any unit or agency of the United States Government, the
following provisions apply. The Government agrees:
(i) if the Software and fonts are supplied to the Department of
Defense (DoD), the Software and fonts are classified as "Commercial
Computer Software" and the Government is acquiring only "restricted rights"
in the Software, its documentation and fonts as that term is defined in
Clause 252.227-7013(c)(1) of the DFARS; and
(ii) if the Software and fonts are supplied to any unit or agency
of the United States Government other than DoD, the Government's rights in
the Software, its documentation and fonts will be as defined in Clause
52.227-19(c)(2) of the FAR or, in the case of NASA, in Clause
18-52.227-86(d) of the NASA Supplement to the FAR.
• Version History
Still to do -
increase to 15 lines/routine
add thesaurus
Yoda:
Finish up Master Yoda
Handle out of disk space errors better
Revamp Yoda’s UI
Master Yoda progress bar needs status display "Parsing" "Sorting" etc.
Temporary files should be placed in the Temporary Items folder
Mike Engber <engber@newton.apple.com>:
App for viewing the database
Font selection (esp a monospaced font)
Way to specify two or more keywords for one entry
Way to escape | characters
Way to more than 10 lines per entry
Better debugging in Master Yoda (display anomolies)
Other:
Search all databases, basically pretend that there is only a single database as much as possible.
Decent documentation (any volunteers?)
Double click STR# for Prefs and Parse Proc files.
Typing in the ObiWan window when a DA is up puts keys into both!
Clicks sometimes go thru to the background app.
Add the appropriate string resource into the ObiWan Preferences and
Pascal Template Procedure so that when you launch them they put up nice
messages saying 'ObiWan Preferences file must be placed in the Obiwan
Folder within your Preferences Folder' and so on.
STR -16397 I think
5.0.1
~Fixed bug where it writed the prefs out continuously
~Fixed "bug" where it couldn't find the System 7.5 WDEF (they moved it!)
5.0.0
~Almost a complete rewrite
~Use TextServicesManager to display the floating window
~Change from INIT/CP to Application
~A way to dynamically switch between insertion procedures.
~add words
~Crashes on LC/6.0.7 when you choose Select Parse Proc.
~colour window
4.0.1
~Support key codes so it works with terminal apps - still doesn’t work with Word :-)
~Include the Force database
~Report errors a bit better
~Fix MasterYoda parse proc crash
4.0.0d5
~Balloon Help everywhere - THANKS QUINN!
~Added C Parse Procedure
~Improved param block parsing
4.0.0d4
~Sound play only once every N minutes...
~Select the destination of the output Force file
~Add param blocks to database.
~Sounds should play asynchronously.
4.0.0d2
~Fix the cmd-enter bug where it chooses the first word instead of the selected word
~Click in the R2D2 icon to turn typing on.
~No way to set the Switch Database hotkey
• Acknowledgements
This program, like many of my others, would never have gotten here without the help of my friends. Thanks!
Thanks to Jager, Quinn, and Rhys for their ideas and suggestions for ObiWan in the initial design phase. Thanks you J&Q for the initial parsing of the PInterfacesHelp file and the colour icons. Thanks also to the UCC, Curtin, Todd (have fun at Momentum!), Steve, c.s.m.p, plaza, ftp.apple.com, Stephen, and anyone who uses ObiWan! Thanks to Greg and the guys at Metrowerks for including ObiWan and giving me a license to their wonderful compiler. ObiWan is written in Metrowerks Pascal - still in its early days, but very nice! Master Yoda is still written in THINK Pascal (it uses Objects)! Special thanks go to those brave souls who risked life and Mac beta testing an unknown program.
